I think the workflow is not so great at the moment. I changed so the rst files are automatically generated from scratch to get all parts in the docs without having to remember to manually modify when you have refactored something.

But then I also added the rst files into version control which I think means they are not generated from scratch unless you remember to first delete all of them, build the docs locally and commit any modified files... So maybe having them in version control is not a good solution.

I think the ideal solution would be to always automatically generate it from scratch and not have anything where manual tweaking is required because people will likely forget to do that and the docs become out of sync with the code. At least until we have reached a more stable version where parts are not significantly refactored anymore.

What do you think? If I understood it correctly the rst files before contained some manual parts to not include some classes?

OK I see. No worries. I only concerns only few 'exclude-members':.
I will see what I can do but the idea is that some fileds/classes need to be excluded as the user does not need to see them.
It would be nice to avoid as much as possible any generated stuff to lie in the github repo.

Do you think it might be possible to name those fields/classes with _ in the beginning and make use of that to automatically exclude them?

I also think generated things should be removed. I only did it because it seemed to be the recommendation when I looked at the different options. But I'm not convinced that it's a good recommendation.

I'm working on it and I can say that autosummary is a pain.
I'm fighting with Jinja templates.
I also would like to exclude things without '_' such as model_config for instance or others fields that the user do not need.
At least give a way to do this.

I also had a lot of issues... There is also autodoc2 which I saw some other packages use. But I'm not sure if that it easier to use. Maybe it always is a pain.

I finally stopped trying to use Jinja templates and autosummary and I wrote a small python program that generates the rst files.
So it is easy to understand and to improve.
It generates tree of toctree and it provides good results.
Tomorrow i will check if internal links in the doc work also as expected.

@TeresiaOlsson
The API reference is OK for me.
There are still duplicate warnings during the doc generation mainly link to wrong docstring in source.

I ended the BPM array stuff.
Here is how it looks.
I can be used as a model to write code snippet, link, etc...